#第 4 章：Skills 安装与管理实践

难度: ⭐ 入门 | 预计阅读: 15 分钟 | 前置章节: [第 3 章](03-Skills 插件体系与批量开发.md)

本章介绍如何安装、管理和维护 OpenClaw Skills，包括从 ClawHub 安装、手动安装、版本管理和安全审查。掌握 Skills 管理是提升 Agent 能力的关键一步。

#4.1 Skills 安装方式

OpenClaw 提供多种 Skill 安装方式，适应不同场景需求。下表汇总了各安装方式的特性对比：

#方式一：ClawHub 安装（推荐）

ClawHub 是 OpenClaw 的官方技能市场，提供经过审核的 Skills：

clawdhub install tavily-search
clawdhub install memory
clawdhub install proactive-agent

安装完成后，Skill 会自动放置到 ~/.openclaw/workspace/skills/ 目录下，并注册到系统配置中。你可以立即在 Agent 对话中使用新安装的能力。

#方式二：npx skills CLI

# 搜索技能
npx skills find "web search"

# 安装技能
npx skills add tavily-search

# 检查更新
npx skills check

# 批量更新
npx skills update

#方式三：手动安装

从 GitHub 或其他来源手动安装：

git clone https://github.com/author/my-skill.git \
  ~/.openclaw/workspace/skills/my-skill

#方式四：MCP 工具集成

通过 McPorter 添加 MCP 服务器（可提供工具级 Skill）：

mcporter config add exa https://mcp.exa.ai/mcp
mcporter config add xiaohongshu http://localhost:18060/mcp

MCP 方式适合集成已有的 REST API 或第三方 AI 工具服务，无需编写完整的 Skill 目录结构。

#4.2 Skills 发现与搜索

找到适合需求的 Skills 是高效使用 OpenClaw 的前提。OpenClaw 提供两种方式发现技能：在线浏览 ClawHub 市场，或通过命令行搜索。推荐先在 ClawHub 上浏览热门技能和分类，找到目标后再用 CLI 安装。

#ClawHub 浏览

访问 https://skills.sh 在线浏览所有可用技能。页面支持按分类、热度、最近更新等维度筛选，同时展示安装量和用户评分。

#命令行搜索

# 搜索包含关键词的技能
npx skills find "search"
npx skills find "automation"
npx skills find "feishu"

#本地已安装列表

查看本机已安装的 Skills 列表有助于了解当前 Agent 的能力范围，避免重复安装。以下命令遍历 Skills 目录并提取每个技能的名称和描述：

ls ~/.openclaw/workspace/skills/
# 详细信息：遍历所有已安装 Skill 并展示描述
for dir in ~/.openclaw/workspace/skills/*/; do
  name=$(basename "$dir")
  if [ -f "$dir/SKILL.md" ]; then
    desc=$(grep -oP 'description:\s*"\K[^"]+' "$dir/SKILL.md" | head -1)
    echo "  📦 $name: $desc"
  fi
done

#4.3 版本管理

Skills 支持语义化版本管理（SemVer），便于追踪变更和控制兼容性。

#版本号含义

#查看当前版本

# 查看单个 Skill 版本
head -10 ~/.openclaw/workspace/skills/tavily-search/SKILL.md

# 查看所有 Skill 版本
npx skills check

#更新策略

定期更新 Skills 可以获取最新的 Bug 修复和功能改进。npx skills check 会对比本地版本与 ClawHub 上的最新版本，列出可更新的技能。对于生产环境，建议先在测试环境验证新版本兼容性后再批量更新。

# 检查可用更新
npx skills check

# 更新所有
npx skills update

# 更新指定 Skill
npx skills update tavily-search

#版本回退

手动安装的 Skills 支持 Git 回退。当更新后的 Skill 出现兼容性问题或行为异常时，可以通过 Git 快速回退到上一个稳定版本。回退前建议记录当前版本号以便后续追踪，回退后需要重启 Gateway 或重新加载 Agent 以使旧版本生效。如果使用 clawdhub install 安装的 Skill，也可以通过指定版本号重新安装来实现降级。

cd ~/.openclaw/workspace/skills/my-skill
git log --oneline
git checkout v1.0.0  # 回退到指定版本

#4.4 安全审查

安装第三方 Skills 前应进行安全审查。OpenClaw 内置了 skill-vetter 技能，专门用于安全检查。

#skill-vetter 审查流程

#使用方法

在安装前，让 Agent 对 Skill 进行审查：

请帮我审查这个 Skill: https://github.com/author/suspect-skill

#安全配置

OpenClaw 提供执行审批机制，配置文件位于 ~/.openclaw/exec-approvals.json：

{
  "autoApprove": ["ls", "cat", "echo"],
  "requireApproval": ["rm", "curl", "wget"],
  "deny": ["rm -rf /"]
}

#最佳实践

• 优先使用 ClawHub 官方审核的 Skills
• 安装前阅读 SKILL.md 了解权限范围
• 对包含 scripts/ 的 Skills 逐一检查脚本内容
• 定期运行 npx skills check 检查安全更新
• 在生产环境中严格限制 autoApprove 列表

#4.5 Skill 配置与 OpenClaw.json

部分 Skills 需要在主配置文件 ~/.openclaw/openclaw.json 中进行额外配置。

#技能启用/禁用

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-xxx"
      },
      "ddg-search": {
        "enabled": true
      },
      "notion": {
        "enabled": false
      }
    }
  }
}

#需要 API Key 的 Skills

#MCP 服务器配置

通过 McPorter 管理的 MCP 型 Skill：

# 查看已配置的 MCP 服务器
mcporter list

# 添加新服务器
mcporter config add <name> <url>

# 调用 MCP 工具
mcporter call 'exa.web_search_exa(query: "AI agents")'

#4.6 实战：搭建搜索技能组合

以搭建完整的搜索能力为例，展示 Skills 安装管理实战。

#目标

构建多引擎搜索能力：Tavily（主力）→ DuckDuckGo（免费备选）→ Exa（MCP）

#Step 1：安装搜索 Skills

# 安装 Tavily（需要 API Key）
clawdhub install tavily-search
# 配置 API Key — 编辑 ~/.openclaw/openclaw.json → skills.entries.tavily.apiKey

# 安装 DuckDuckGo（零依赖）
clawdhub install ddg-web-search

# 安装 Exa MCP
mcporter config add exa https://mcp.exa.ai/mcp

#Step 2：验证安装

安装完成后，务必逐一验证每个搜索引擎是否可以正常工作。验证步骤包括确认脚本可执行、API Key 已正确配置、以及网络连通性正常。如果某个引擎测试失败，可先跳过继续验证其他引擎，确保至少有一个可用的搜索后端。

# 测试 Tavily
node ~/.openclaw/workspace/skills/tavily-search/scripts/search.mjs "test"

# 测试 DuckDuckGo
curl -sL "https://lite.duckduckgo.com/lite/?q=test&kl=au-en"

# 测试 Exa
mcporter call 'exa.web_search_exa(query: "test", numResults: 3)'

#Step 3：配置优先级

Agent 会根据 SKILL.md 的 triggers 和上下文自动选择合适的搜索引擎。可在对话中指定：

搜索 "OpenClaw 教程"              ← Agent 自动选择
用 Tavily 搜索 "OpenClaw 教程"    ← 指定引擎

#进阶：安装机制深入

理解 Skills 安装的底层机制有助于排查安装问题和优化管理流程：

• 安装流程：openclaw skill install 命令执行时依次完成 下载/克隆 → 校验 manifest → 解析依赖 → 安装依赖 → 注册到技能表 五个阶段，任一阶段失败会自动回滚。
• 版本管理：ClawHub 上的 Skill 支持语义化版本，openclaw skill install name@1.2.0 可安装指定版本，openclaw skill update 默认升级到最新兼容版本。
• 离线安装：在无网络环境下，可将 Skill 目录打包为 .tar.gz，通过 openclaw skill install --from-archive ./skill.tar.gz 安装部署。
• 依赖解析策略：当多个 Skill 依赖同一工具的不同版本时，系统采用就近原则，优先使用 Skill 目录内的本地依赖。

#注意事项与常见错误

安装和管理 Skills 时需要注意以下事项，避免常见问题：

⚠️ 注意：安装第三方 Skill 前应审查其 manifest.json 和脚本内容，确认无恶意代码。生产环境建议仅从可信来源安装。

#进阶：技能安装与版本管理原理

深入了解技能的安装机制有助于排查安装失败问题：

#注意事项与常见错误

技能管理的常见错误：

#进阶：安装机制与版本管理原理

深入技能安装机制有助于排查安装失败：

#注意事项与常见错误

技能管理常见错误：

#实操练习

通过以下练习动手掌握 Skills 的完整生命周期管理。

#练习 1：安装并测试一个免费搜索 Skill

1. 使用 ClawHub 安装 ddg-web-search：

   clawdhub install ddg-web-search

2. 确认 Skill 已成功安装，查看其描述文件：
   ```bash
   ls ~/.openclaw/workspace/skills/ddg-web-search/
   cat ~/.openclaw/workspace/skills/ddg-web-search/SKILL.md

3. 在 Agent 对话中测试搜索功能：

   用 DuckDuckGo 搜索 "OpenClaw 最新版本"

4. 验证搜索结果正常返回，记录返回条数和内容质量。

### 练习 2：对第三方 Skill 进行安全审查

1. 在 GitHub 上找一个第三方 Skill 仓库（可使用 `npx skills find` 搜索）。
2. 请求 Agent 进行安全审查：
   ```text
   请帮我审查这个 Skill: https://github.com/example/example-skill

3. 仔细阅读审查报告，重点关注：
   • 是否包含危险命令（rm -rf、eval、exec）
   • 网络请求的目标地址是否合理
   • 文件读写范围是否受限于工作目录
4. 根据审查结果决定是否安装，记录审查判断依据。

#练习 3：搭建多引擎搜索并对比效果

1. 按照 4.6 节完整步骤安装 Tavily 和 DuckDuckGo 两个搜索引擎。
2. 分别用两个引擎搜索相同关键词并记录结果：

   用 Tavily 搜索 "AI agent framework 2026"
   用 DuckDuckGo 搜索 "AI agent framework 2026"

3. 从以下维度对比结果：

   | 维度 | Tavily | DuckDuckGo |
   |------|--------|------------|
   | 返回条数 | | |
   | 结果质量 | | |
   | 响应速度 | | |
   | 是否需要 API Key | 是 | 否 |

4. 在 `openclaw.json` 中调整搜索引擎优先配置，验证切换效果。

---

## 常见问题 (FAQ)

**Q1: 安装 Skill 后提示找不到，Agent 无法使用怎么办？**

A: 按以下顺序排查：
1. 确认 Skill 目录下存在 `SKILL.md` 文件：`ls ~/.openclaw/workspace/skills/<name>/SKILL.md`
2. 重启 Agent 或新开一个会话（已加载的 Session 不会自动发现新 Skill）
3. 检查 `openclaw.json` 中是否有 `"enabled": false` 的配置覆盖

**Q2: API Key 应该放在环境变量还是 OpenClaw.json 中？**

A: 两种方式都支持，环境变量优先级更高。推荐做法：
- **开发环境**：写入 `openclaw.json` 的 `skills.entries` 方便调试
- **生产环境**：使用环境变量，避免密钥写入配置文件
```bash
export TAVILY_API_KEY="tvly-your-key-here"

Q3: 如何完全卸载一个 Skill？

A: 分两步操作：

# 1. 删除 Skill 目录
rm -rf ~/.openclaw/workspace/skills/<skill-name>

# 2.（可选）从 openclaw.json 中移除对应配置项
# 编辑 ~/.openclaw/openclaw.json，删除 skills.entries 中的对应条目

Q4: MCP 服务器连接超时怎么排查？

A: 按以下步骤逐一排查：

# 1. 检查 URL 是否可达
curl -I <mcp-url>

# 2. 查看 McPorter 状态
mcporter list

# 3. 检查防火墙与网络
ping <mcp-host>

如果是 localhost 服务，确认对应进程正在运行。

Q5: 多个 Skills 提供相同功能会冲突吗？

A: 不会冲突。OpenClaw 的 Skill 系统基于目录隔离，各 Skill 独立运行。当多个 Skill 提供相似能力时，Agent 会根据对话上下文和 SKILL.md 中的 triggers 自动选择最合适的一个。你也可以在对话中明确指定使用哪个 Skill。

#Troubleshooting

#Skill 安装后 Agent 不识别

原因：Skill 目录缺少 SKILL.md 或文件内容格式有误。

排查：

ls ~/.openclaw/workspace/skills/<skill-name>/SKILL.md
# 检查文件头部是否包含 name 和 description 字段
head -10 ~/.openclaw/workspace/skills/<skill-name>/SKILL.md

#npx skills find 无结果但 ClawHub 网页有

原因：CLI 搜索依赖本地索引缓存，可能未更新。

解决：

npx skills cache clear
npx skills find "keyword"

#MCP 工具调用超时

排查：确认 MCP 服务器进程正在运行，并检查端口连通性：

curl -s http://localhost:18060/mcp | head -5
mcporter config list  # 确认配置的 URL 正确

#参考资料

• ClawHub 官方技能市场 — 浏览和安装官方审核的 Skills
• OpenClaw Skills 开发文档 — Skill 结构规范与开发指南
• McPorter MCP 集成指南 — MCP 服务器配置与工具调用
• 语义化版本管理规范 (SemVer) — 版本号命名规范参考
• OpenClaw GitHub 仓库 — 源码与 Issue 追踪

#本章小结

• Skills 安装方式：掌握 ClawHub、npx CLI、手动克隆、MCP 集成四种安装方式，按需选择
• Skills 发现与搜索：通过 ClawHub 网站和命令行快速定位所需技能
• 版本管理：使用语义化版本管理，支持检查更新、批量更新与版本回退
• 安全审查：安装前通过 skill-vetter 进行代码审查和红旗检测，保障系统安全
• 配置管理：在 OpenClaw.json 中管理 Skill 的启用状态、API Key 和 MCP 服务器
• 实战组合：通过多引擎搜索组合展示 Skill 协同工作的最佳实践
• 遇到问题时，善用 openclaw doctor 进行诊断。